package com.kexio.auth.annotation;

import java.lang.annotation.Documented;
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

/**
 * 公开API注解
 * 
 * 标注在控制器方法或类上，表示该接口为公开访问，
 * 无需进行JWT Token验证和权限检查。
 * 
 * 通常用于：
 * - 登录接口
 * - 注册接口  
 * - 验证码接口
 * - 健康检查接口
 * - 公开的API文档接口
 * 
 * <pre>
 * &#64;PostMapping("/login")
 * &#64;PublicApi
 * public Result&lt;LoginResponse&gt; login(&#64;RequestBody LoginRequest request) {
 *     return authService.login(request);
 * }
 * 
 * &#64;GetMapping("/captcha")
 * &#64;PublicApi(description = "获取验证码")
 * public Result&lt;CaptchaResponse&gt; getCaptcha() {
 *     return captchaService.generateCaptcha();
 * }
 * </pre>
 * 
 * @author Kexio Team
 * @since 1.0.0
 */
@Target({ElementType.METHOD, ElementType.TYPE})
@Retention(RetentionPolicy.RUNTIME)
@Documented
public @interface PublicApi {
    
    /**
     * 接口描述
     * 
     * 用于标识该公开接口的用途和说明
     * 
     * @return 接口描述信息
     */
    String description() default "";
    
    /**
     * 是否记录访问日志
     * 
     * @return true-记录访问日志，false-不记录访问日志
     */
    boolean logAccess() default true;
    
    /**
     * 是否启用IP白名单检查
     * 
     * @return true-检查IP白名单，false-允许所有IP访问
     */
    boolean checkIpWhitelist() default false;
    
    /**
     * IP白名单
     * 
     * 当checkIpWhitelist=true时生效，支持：
     * - 具体IP：192.168.1.100  
     * - CIDR格式：192.168.1.0/24
     * - IP段：192.168.1.1-192.168.1.100
     * 
     * @return IP白名单数组
     */
    String[] ipWhitelist() default {};
    
    /**
     * 是否启用限流
     * 
     * @return true-对公开接口进行限流，false-不限流
     */
    boolean enableRateLimit() default false;
    
    /**
     * 限流次数（每分钟）
     * 
     * 当enableRateLimit=true时生效
     * 
     * @return 每分钟最大请求次数
     */
    int rateLimit() default 100;
    
    /**
     * 版本号
     * 
     * 用于API版本管理，支持版本控制和兼容性检查
     * 
     * @return API版本号
     */
    String version() default "1.0";
}
